Starting and Ending Draw Regions11

Generally, there is one draw region per monitor. At any particular time, however, a window associated with a draw context may not appear in the active monitor. Thus one or more draw regions may be inactive at a given time and should be explicitly ignored by the renderer. You can use the Q3XDrawRegion_IsActive function to determine if a given draw region is currently active.

For active draw regions, one of two calls must be made before rendering into the draw region, regardless of how much draw region functionality is required: Q3XDrawRegion_Start or Q3XDrawRegion_StartAccessToImageBuffer.

You can use the Q3XDrawRegion_Start function if double-buffering and image access services are not needed; it just returns a pointer to the draw region descriptor TQ3XDrawRegionDescriptor (link) . However, the function described below is more useful for most plug-in renderers.

The Q3XDrawRegion_StartAccessToImageBuffer function provides image access and double-buffering services for your renderer. Besides returning a pointer to the draw region descriptor, it also returns a pointer to the raster image into which rendering occurs. For single-buffering, this is a pointer to video memory; for double buffering, it is a pointer to a system-allocated back buffer. The double-buffering process is handled by the draw region. Most plug-in renderers must use the Q3XDrawRegion_StartAccessToImageBuffer function instead of Q3XDrawRegion_Start .

Once a renderer is done with a draw region, it must call the Q3XDrawRegion_End function.

Q3XDrawRegion_IsActive

The Q3XDrawRegion_IsActive function lets you determine whether a draw region is active or inactive. If it is inactive, the renderer may ignore it.



 
TQ3Status Q3XDrawRegion_IsActive(

                     TQ3XDrawRegion    drawRegion,

                     TQ3Boolean        *isActive);

drawRegion: A draw region.
isActive: Returns kQ3True if the draw region is active; kQ3False otherwise.

DESCRIPTION

The Q3XDrawRegion_IsActive function returns, in the isActive parameter, kQ3True if the draw region designated by drawRegion is active and kQ3False otherwise.

Q3XDrawRegion_Start

The Q3XDrawRegion_Start function returns a draw region descriptor to a renderer that does not require double-buffering or image access.



 
TQ3Status Q3XDrawRegion_Start(

                     TQ3XDrawRegion              drawRegion,

                     TQ3XDrawRegionServices      services,

                     TQ3XDrawRegionDescriptor    **descriptor);

drawRegion: A draw region.
services: Draw region services requested (see [link] ).
descriptor: On return, a draw region descriptor (see [link] ).

DESCRIPTION

The Q3XDrawRegion_Start function returns, in the descriptor parameter, a pointer to a draw region descriptor for the draw region designated by drawRegion.

The Q3XDrawRegion_Start function may be called if double-buffering and image access services are not needed. The renderer must provide a valid value in the services parameter, requesting if clearing or DDSurface locking is required (see [link] ).

This function is rarely used, because the renderer is then required to do all the work of allocating, locating, clearing, and double buffering the image raster. Most plug-in renderers use the Q3XDrawRegion_StartAccessToImageBuffer function instead of Q3XDrawRegion_Start.

Q3XDrawRegion_StartAccessToImageBuffer

The Q3XDrawRegion_StartAccessToImageBuffer function provides image access and double-buffering services for a renderer. In addition to returning a pointer to the draw region descriptor, it also returns a pointer to the raster image into which rendering occurs is returned. In the case of single-buffering, this is a pointer to the video memory; in the case of double-buffering, it is a pointer to a system-allocated back buffer. All double-buffering, etc., is now handled by the draw region.



 
TQ3Status Q3XDrawRegion_StartAccessToImageBuffer(

                     TQ3XDrawRegion              drawRegion,

                     TQ3XDrawRegionServices      services,

                     TQ3XDrawRegionDescriptor    **descriptor,

                     void                        **image);

drawRegion: A draw region.
services: Draw region services requested (see [link] ).
descriptor: On return, a draw region descriptor (see [link] ).
image: On return, a pointer to the target raster image.

DESCRIPTION

The Q3XDrawRegion_StartAccessToImageBuffer function returns a draw region descriptor in the descriptor parameter and a pointer to the renderer's target raster in the image parameter, both for the draw region designated by drawRegion.

SPECIAL CONSIDERATIONS

Most plug-in renderers use the Q3XDrawRegion_StartAccessToImageBuffer function instead of Q3XDrawRegion_Start .

Q3XDrawRegion_End

A renderer must call the Q3XDrawRegion_End function when it has finished with a draw region.



 
TQ3Status Q3XDrawRegion_End(

                     TQ3XDrawRegion    drawRegion);

drawRegion: A draw region.

DESCRIPTION

After rendering, the Q3XDrawRegion_End function performs internal clean-up and memory release for the draw region designated by drawRegion.